Skip to content
This repository has been archived by the owner on Oct 17, 2020. It is now read-only.

en | Development

Jump to bottom
Chris Tomlinson edited this page Sep 2, 2015 · 18 revisions

KeeFox is open source and we encourage interested developers to build and maybe even contribute to the project.

Please feel free to add or improve any KeeFox features on a github fork. You can improve the chances of a pull request being accepted if you work on a feature that has a corresponding issue. Look for something that interests you which is not already assigned to a developer but is assigned to a milestone (including "future"). Of course, it would be best to post a comment on the issue before getting started just in case someone else is already working on the feature you're interested in adding or improving.

If you don't see an issue for the feature or bug fix you'd like to develop please just post a new one and we can discuss any implications or details before you get started.

See also: Github issue tracker

If you are interested in validating the existing source code then please feel free and just ask in the forums or on github if you need any help understanding any aspect of the code.

Overview

To develop KeeFox you can choose from a variety of approaches and tools, depending upon what you want to achieve and your preferred development environment.

The guide below assumes you are using a Windows 7+ environment but the majority of information applies across other platforms too.

There are a handful of overall strategies to developing KeeFox, ranging from very basic file manipulation to complex compilation of a variety of programs. To get started, you need to decide which strategy to follow. The table below will help you to do this by providing guidance on the sorts of outcomes that you can achieve with each strategy. Strategies are listed from left to right in rough order of complexity so just find the strategy furtherest to the left that meets your needs.

Once you know the strategy to follow, each section below will outline what you need to do.

Use / Strategy Make a small one-off change to the add-on Develop the KeeFox add-on Develop and package the KeeFox add-on Develop and package the KeeFox add-on and KeePassRPC plugin
Small scale experimentation x x x x
Simple customisation for your personal preference or requirements x x x x
Testing language translations x x x x
Make a change that you want to be applied to each future KeeFox release x x x
Produce an addon XPI file for installation on extra test machines or Firefox profiles x x
Make changes to the KeePassRPC plugin x

Compilation of the various utility applications are not covered in this guide. If you want to work with them, you'll need to dive into the KeeFox-Extras.sln but bear in mind these have not been re-built since Visual Studio 2010 (and I have no intention to rebuild them if it can be avoided since that would require going through the hassle of a fresh executable signing procedure).

Since Firefox 41, it is no longer possible to develop the KeeFox addon unless you use the Developer Edition and disable extension signing checks as explained in https://wiki.mozilla.org/Addons/Extension_Signing

Visual Studio versions

For minor development work, mainly that focussed on Javascript/HTML/XUL modiifcations, you should not need Visual Studio at all. For other work you should use Visual Studio 2013. The projects are designed for use with the free Express versions although the new community free edition might also work (and I anticipate migrating the projects to that edition eventually in order to simplify the build process to a single Visual Studio instance).

Visual Studio 2010 users should see the dedicated section below.

Make a small one-off change to the add-on

  • Download the KeeFox XPI file from https://addons.mozilla.org/en-US/firefox/addon/keefox/versions/
    • right click and save as to force the download rather than install
  • Rename the file to KeeFox.zip
  • Extract the zip file
  • Apply your change
  • Bundle the files into a new KeeFox.zip file
    • make sure it contains the individual files and folders, not just a single parent folder
  • Rename the file to KeeFox-modified.xpi
  • Drag and drop the new XPI file into Firefox to install it

Develop the KeeFox add-on

-> Unsure what git is or want to avoid using it for the time being? For minor changes, experimentation and debugging you could follow the steps in Make a small one-off change to the add-on or work with a hybrid setup using a proxy file and the extracted contents of the official XPI. Bear in mind that following the full git-based approach below will make it easier for you to get your changes incorporated into the main addon so you might save time in the long run by following this approach.

  1. Debug/develop with Firefox developer edititon or Set up a testing Firefox profile
  2. Pull the latest source code from git into a local development folder (and make sure the add-on proxy file created in step 1 points to the correct folder)
  3. For smaller scale development you'll probably be happy just editing the relevant files with a text editor but if you want to use Visual Studio 2013 Express Web for Intellisense, syntax highlighting, etc. follow steps 3-7 in the "Develop and package the KeeFox add-on" strategy below.

Develop and package the KeeFox add-on

  1. Set up a testing Firefox profile
  2. Pull the latest source code from git into a local development folder
  3. Install Visual Studio 2013 Express Web (update 2+)
  4. Actually it is possible to package the XPI without the aid of Visual Studio but taking the time to install and use it now could be beneficial because:
    1. it is essential for later strategies that need to modify the KeePassRPC plugin too
    2. the information below can be used as a head start configuration for debugging multiple versions of Firefox
    3. it is the same configuration used to package the official versions of KeeFox
  5. Create a "Firefox addon\Firefox addon.csproj.user" file in the same directory as the "Firefox addon\Firefox addon.csproj" file
    1. This allows Visual Studio to automatically take the appropriate action when you ask it to debug KeeFox.
    2. The example below is complete but you will probably want to tweak a few of the settings in order to match the install locations of the various versions of Firefox installed on your system and the name of your testing profile.
  6. Open "Firefox addon\Firefox addon.csproj" in Visual Studio 2013 Express Web
  7. Press debug (run) while in "Release", "Beta" or "Aurora" mode to launch Firefox.
  8. Install ZipGenius command line client at "c:\Program Files (x86)\ZipGenius 6\zg.exe" (or modify the post-build step to use a different command line zip client). TODO: Probably neater to move to an MSBuild approach using system.io.compression.zipfile
  9. Build in "XPI" configuration to package up the XPI.

"Firefox addon\Firefox addon.csproj.user" sample

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <ProjectView>ProjectFiles</ProjectView>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Aurora|AnyCPU'">
    <StartProgram>C:\Program Files (x86)\Aurora\firefox.exe</StartProgram>
    <StartAction>Program</StartAction>
    <StartArguments>-P "Test User" -purgecaches --no-remote</StartArguments>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Beta|AnyCPU'">
    <StartProgram>C:\Program Files (x86)\Mozilla Firefox Beta\firefox.exe</StartProgram>
    <StartAction>Program</StartAction>
    <StartArguments>-P "Test User" -purgecaches --no-remote</StartArguments>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Release|AnyCPU'">
    <StartProgram>C:\Program Files (x86)\Mozilla Firefox\firefox.exe</StartProgram>
    <StartAction>Program</StartAction>
    <StartArguments>-P "Test User" -purgecaches --no-remote</StartArguments>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'XPI|AnyCPU'">
    <StartProgram>C:\Program Files (x86)\Mozilla Firefox Beta\firefox.exe</StartProgram>
    <StartAction>Program</StartAction>
    <StartArguments>-P "Test User" -purgecaches --no-remote</StartArguments>
  </PropertyGroup>
      <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Nightly|AnyCPU'">
        <StartProgram>C:\Program Files %28x86%29\Nightly\firefox.exe</StartProgram>
        <StartArguments>-P "Test User" -purgecaches --no-remote</StartArguments>
        <StartAction>Program</StartAction>
      </PropertyGroup>
</Project>

Develop and package the KeeFox add-on and KeePassRPC plugin

  1. Ensure you've done steps 1-9 in the section above (Develop and package the KeeFox add-on)
  2. Install Visual Studio 2013 Express Desktop (update 2+)
  3. Either...
    1. create a symlink from C:\Program Files (x86)\KeePass Password Safe DEV\KeePass.exe to your KeePass.exe location
    2. update the project reference, post-build script and csproj.user config to point to your KeePass.exe location
  4. Create a subfolder called "deps" inside the Firefox addon\KeeFox folder
  5. Create a "KeePassRPC\KeePassRPC.csproj.user" file in the same directory as the "KeePassRPC\KeePassRPC.csproj" file
    1. This allows Visual Studio to automatically take the appropriate action when you ask it to debug KeePassRPC using KeePass.
    2. The example below is complete but you may want to tweak the command line settings if they don't suit your environment.
  6. Open "KeePassRPC\KeePassRPC.csproj" in Visual Studio 2013 Express Desktop (with elevated privileges since it needs to copy files in to C:\Program Files (x86)\KeePass Password Safe DEV\plugins)
  7. Press debug (run) while in "Debug" mode to launch KeePass using your KeePassRPC plugin build.
    1. You can run in ReleasePLGX configuration too but it's rarely useful since the debugger is unable to step into any of the dynamically compiled code.
  8. A complete packaging operation to generate a new "XPIs\current.xpi" file is:
    1. Ensure the utility executables are in the "Firefox addon\KeeFox\deps" folder
    2. Build KeePassRPC in the "ReleasePLGX" configuration
    3. Build KeeFox in the "XPI" configuration

"KeePassRPC\KeePassRPC.csproj.user" sample

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <StartArguments>-debug -KeePassRPCPort:12540 -KeePassRPCWebSocketPort:12547 -KPRPCDebug="c:\temp\kprpcLog.txt"</StartArguments>
    <StartAction>Program</StartAction>
    <StartProgram>C:\Program Files (x86)\KeePass Password Safe 2 DEV\KeePass.exe</StartProgram>
  </PropertyGroup>
  <PropertyGroup>
    <PublishUrlHistory>
    </PublishUrlHistory>
    <InstallUrlHistory>
    </InstallUrlHistory>
    <SupportUrlHistory>
    </SupportUrlHistory>
    <UpdateUrlHistory>
    </UpdateUrlHistory>
    <BootstrapperUrlHistory>
    </BootstrapperUrlHistory>
    <FallbackCulture>en-US</FallbackCulture>
    <VerifyUploadedFiles>false</VerifyUploadedFiles>
    <ProjectView>ProjectFiles</ProjectView>
    <ErrorReportUrlHistory />
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'ReleasePLGX|AnyCPU' ">
    <StartProgram>C:\Program Files (x86)\KeePass Password Safe 2 DEV\KeePass.exe</StartProgram>
    <StartAction>Program</StartAction>
    <StartArguments>-KeePassRPCWebSocketPort:7438</StartArguments>
  </PropertyGroup>
</Project>

Set up a testing Firefox profile

An easier but slightly less flexible approach is described in Debug/develop with Firefox developer edititon

NB: If you are working in Thunderbird, just substitute Thunderbird wherever it says Firefox.

  1. Create a new profile in Firefox. For all the gory details, click here. For the essential steps, read on.
    1. From a command prompt or Run (WIN+R in windows, ALT+F2 in linux), run firefox -P -no-remote.
    2. In the dialog that opens, click the Create Profile... button.
    3. Click Next, then enter 'Test User' as the new profile name and then click Finish.
    4. Click Exit to close the Profile Manager. We don't actually want to start Firefox yet.
  2. Create a proxy file to point to your dev directory.
    1. Browse to the extensions directory of the profile that you just created (need help finding it?)
    2. If the folder 'extensions' does not exist, create it.
    3. Create a new file named keefox@chris.tomlinson (name HAS to match id in install.rdf). Set the contents of the file to the full path to the KeeFox addon source code directory (e.g. C:\dev\KeeFox\Firefox addon\KeeFox).
  3. Start Firefox using your new profile. firefox -P "Test User" -no-remote (-no-remote lets you open your profile in a new process so you can have multiple instances of FireFox running at once)
  4. It should open with an Install Add-on tab asking you to 'Allow this installation'. If you don't see this, you probably spelt something wrong and will have to create the proxy file again (it gets deleted automatically).
  5. Restart Firefox and get hacking. (You will have to restart Firefox every time you make changes)

Debug/develop with Firefox developer edititon

  1. Install the developer edition (previously known as Aurora)
  2. Create a proxy file to point to your dev directory.
    1. Browse to the extensions directory of the dev-edition-default profile that you just created (need help finding it?)
    2. Create a new file named keefox@chris.tomlinson. Set the contents of the file to the full path to the KeeFox addon source code directory (e.g. C:\dev\KeeFox\Firefox addon\KeeFox).
  3. Start Firefox developer edition. It should open with an Install Add-on tab asking you to 'Allow this installation'. If you don't see this, you probably spelt something wrong and will have to create the proxy file again (it gets deleted automatically).
  4. Restart Firefox and get hacking. (You will have to restart Firefox every time you make changes).
  5. For quick experimentation, use the built-in Browser toolbox which you can find in the developer tools menu on the toolbar.

Version numbering

If you make changes to the KeePassRPC plugin you will need to increment the version number in a few places in order to ensure that your new version is installed correctly by the updated version of KeeFox.

To increment the version number in all locations look in:

  • AssemblyInfo.cs: AssemblyFileVersion attribute

  • KeePassRPCExt.cs: PluginVersion property

  • kprpcClient.js: clientVersion - near the top of the file

  • install.rdf (you'll want to change this even if you make no changes to KeePassRPC)

The version number of KPRPC does not have to match that of KeeFox (install.rdf) but it should not be higher.

In other words, you should never increment the KPRPC version number without upgrading the main KeeFox add-on version number but it is OK to upgrade the KeeFox add-on version number without upgrading the KPRPC version.

Visual Studio 2010 users

The KeeFox.sln file should still load up the correct projects at the time of writing but it'll become increasingly likely that you'll need to manually adjust a variety of settings and add/remove changed files before you'll be able to get it to build.

To reduce confusion, I intend to remove the 2010 project files in around one year (mid 2015) so please migrate to a newer build system by then.

The information below is retained for reference for users of older versions of Visual Studio.

Building KeeFox

KeeFox is built using Visual Studio 2010. Free versions or the MSBuild command line utility should work but are unlikely to be as easy to get started with as the paid version of Visual Studio. You should be able to use newer versions of Visual Studio but any pull requests you submit for inclusion in the main project must work with Visual Studio 2010.

The projects and solution file are configured to ease the automatic build of the multiple components required to make KeeFox work.

You should read about the different KeeFox components.

You can fork the source code from Github. We recommend reviewing the post-build tasks before building KeeFox.

The "Release" configuration and "ReleasePLGX" configuration are similar except:

  1. "Release" will produce a KeePassRPC.DLL file during a KeePassRPC post-build event (permits debugging)

  2. "ReleasePLGX" results in a KeePassRPC.PLGX file during a KeePassRPC post-build event

  3. "ReleasePLGX" packages the necessary files into an XPI file during a "Firefox addon" post-build event

No other solution configurations are currently used.

VS2010 does not reliably run post-build events for projects where it determines that no relevant code has changed. JavaScript, XUL, etc. does not appear to be relevant so to ensure your XPI package is actually updated you will need to re-build.

The "Firefox addon" post-build task expects to find the command line version of ZipGenius 6 at "c:\Program Files (x86)\ZipGenius 6\zg.exe". You can modify the path, create a symlink, use an alternative command line zip utility or (if you're more interested in experimenting with KeePassRPC) just skip the XPI packaging step altogether.

WARNING!

OLD INFORMATION

The information in this Wiki is out of date.

It is only of interest if you are using the old add-on called KeeFox in a very old (insecure) version of Firefox or other browsers based on the old Firefox XUL technology.

Read the manual for Kee and KeeBird instead.

Clone this wiki locally